home *** CD-ROM | disk | FTP | other *** search
/ LSD Docs / LSD Docs.iso / FILEZ / lsd06.dms / lsd06.adf / 31 < prev    next >
Text File  |  1988-02-16  |  32KB  |  721 lines
  1.                         POWER PACKER 2.3B USER MANUAL
  2.  
  3. Typed in by The author. Edited by PARASITE.
  4.  
  5.  
  6. Preface
  7.      Congratulations, you have just obtained a copy of PowerPacker 2.3b,
  8. PowerPeak's command and data cruncher for the Amiga.  If you have suggestions
  9. or remarks about this program, or if you find any bugs, please let me know.
  10.      This version of PowerPacker is shareware, this means that if you use it
  11. a lot I would appreciate it if you'd send me a contribution of $10 US or the
  12. same amount in any other currency.  This money will enable me to produce more
  13. programs on the Amiga.  If you send $15 US ($20 US overseas) I will send you
  14. the latest version of PowerPacker.  Please send money by international money
  15. order, EuroCheck (in Belgian Francs (BF) !!!!!) or cash, it's difficult for
  16. me to cash in other checks.  If you send for an update please state your
  17. current version, if there is no higher version at the time I get your letter
  18. I won't reply until I finish the next version, so don't be alarmed if it
  19. takes a while !
  20.      If  you want to use PowerPacker for commercial purposes you need written
  21. permission.
  22.  
  23.      Write to the following address:
  24.  
  25.                                 Nico François
  26.                                 Corbielaan 13
  27.                              3060 Bertem BELGIUM
  28.  
  29. CONTENTS
  30.  
  31. 1. The Packer
  32.      1.1 An introduction
  33.      1.2 The file requester
  34.      1.3 The basic menus
  35.           1.3.1 Project
  36.           1.3.2 Prefs
  37.           1.3.3 Crypt
  38.  
  39. 2. Recrunch
  40.      2.1 How ?
  41.      2.2 Why ?
  42.  
  43. 3. The HunkLab
  44.      3.1 Preferences
  45.      3.2 Process file
  46.  
  47. 4. The Script Menu
  48.  
  49. 5. The Supervisor Window
  50.  
  51. 6. A Sample Session
  52.  
  53. 7. PowerPacker 2.3b & the CLI
  54.  
  55. 8. PowerPacker 2.3b & other programs
  56.      8.1 Introduction
  57.      8.2 The function
  58.      8.3 Loading encrypted files
  59.      8.4 Compiling and linking
  60.      8.4 An example
  61.  
  62. 1. THE PACKER
  63.  
  64. 1.1 AN INTRODUCTION
  65.      PowerPacker is a userfriendly command and data cruncher, this means a
  66. menu driven utility that can crunch almost any file on your disks.  It can be
  67. started from the CLI or the WorkBench, just type it's name in the CLI window
  68. or doubleclick it's icon.  PowerPacker will detach itself from the CLI so you
  69. can close the CLI window.  When you use it for the first time it's best to
  70. maintain a certain order in your actions (as we will see in chapter 6 of this
  71. document):
  72.  
  73.   (a) Check the packer options at the beginning of a session (Prefs menu)
  74.   (b) Load the file from disk (Project menu)
  75.   (c) Wait for the file to (de)crunch.
  76.   (d) Save the file back to disk (Project menu)
  77.  
  78.      Apart from crunching, you can also recrunch files that were crunched by
  79. most other crunchers.
  80.      The HunkLab enables you to e.g. force code or data in chip ram.
  81.      The script allows you to e.g. crunch a dozen of files overnight.
  82.  
  83.      Before I demonstrate how to use PowerPacker, let's look at the file
  84. requester and a brief overview of the menus and capabilities.
  85.  
  86. 1.2 THE FILE REQUESTER
  87.     Whenever you are required to enter a filename, the packer sets up a file
  88. requester.  This requester automatically contains all devices connected to
  89. your Amiga and lists all the files (and their length) of a selected
  90. directory.  You don't have to wait for the directory read to end.  You can
  91. select a file or directory the moment you see it, or you can enter it in the
  92. appropriate string gadget.
  93.     However, if you wait for the directory read to end and quit the file
  94. requester, the next time you use it all the files will still be there, so you
  95. don't have to wait for the directory to be read again (This is very useful
  96. when you are recording a script, as you'll see later).  This feature has one
  97. disadvantage :  if files are changed or added to the selected directory they
  98. won't be shown in the list, or they will be shown with the wrong filelength,
  99. the next time the requester appears.  Therefore, if you think anything has
  100. been changed to the selected directory, use the 'GET DIR' gadget to re-read
  101. the directory.  (E.g.  when you save a crunched file on top of the old one,
  102. the old file length will be shown in the requester.)
  103.      When the 'Sort Files' switch in the prefs menu is checked the files will
  104. be alphabetically sorted in the requester.  This switch is present because
  105. some people don't like the files being sorted and jumping up and down the
  106. requester, they think it's annoying to try and catch the file you want. (and
  107. they are right of course :-)
  108.  
  109. 1.3 THE BASIC MENUS
  110.  
  111. 1.3.1 PROJECT
  112.  
  113.     The project menu contains the file manipulation options.  Most of them
  114. speak for themselves:
  115.  
  116.   Load      ->  Load a file from disk and start the (de)crunching.
  117.   Save      ->  Save the (de)crunched or processed file in memory to disk.
  118.   Delete    ->  Delete a file from disk.
  119.   WorkBench ->  Open or close WorkBench if possible. (Adds 42K !)
  120.   Sleep     ->  Put PowerPacker to sleep on the WorkBench Screen, this
  121.                 frees 40-50K.
  122.                 WARNING: All buffers will be deallocated, so you are advised
  123.                          to save things first.
  124.   About...  ->  Show general information and my address.
  125.   Quit      ->  Quit the program.
  126.  
  127. 1.3.2 PREFS
  128.      The prefs menu contains all the (de)cruncher settings.  You can select
  129. to (de)crunch command files or a data files.  If you want the crunched
  130. version of your file to be executable, select 'Command file'.  Now
  131. PowerPacker knows it has to add a decrunch header (572 bytes).  If the file
  132. you want to crunch only contains data (e.g. source codes of your programs),
  133. select the 'Data file' option.  This can be handy if you're going to use the
  134. PowerPacker CLI commands.  I'll discuss these commands in chapter 7 of this
  135. document.  Finally you have to choose whether you want to crunch or decrunch
  136. the load file.
  137.  
  138. NOTE: - PowerPacker will automatically decrunch a previously crunched
  139.         file.  You don't have to select crunch or decrunch mode anymore as
  140.         in PowerPacker 2.0a.
  141.  
  142.      The 'Decrunch Color' submenu contains the following options :
  143.  
  144.   Color 0   ->  The background color will change while decrunching
  145.   Color 1   ->  The text color changes
  146.   Pointer   ->  Only the mousepointer's color changes
  147.   Scroll    ->  Handy for decrunching a demo (just try it out !)
  148.   None      ->  If your eyes are wearing out.
  149.  
  150.      These options indicate what color will flash when a file is decrunched.
  151. You can change this option before saving a crunched file, so you can save a
  152. version of your crunched program that flashes in color 1, and one that
  153. flashes in the mouse pointer.  The default value is 'Pointer'.
  154.  
  155.      In the efficiency submenu you will find the following possibilities :
  156.  
  157.   Fast      ->  Use for small files, or for quick crunch.
  158.   Mediocre  ->  Better but slower.
  159.   Good      ->  Default, gains 40-50% in most cases.
  160.   Very Good ->  Also very slow !
  161.   Best      ->  Advised for script use only, ultra slow !!!
  162.  
  163. NOTE: - 'Fast' is approx. 4 times faster than 'Good', 'Very Good' is
  164.         2 times slower and 'Best' 4 times.
  165.       - 'Best' isn't always the best.  Small files crunch best with
  166.         'Very Good' or even 'Good'.
  167.  
  168.      The remaining preference switches:
  169.  
  170.   Data suffix  -> Attach '.pp' suffix to data files after crunching or remove
  171.                   '.pp' after decrunching.  It is advised that you leave this
  172.                   switch on so you can easily spot crunched data files.
  173.   Encrypt Data -> See section 1.3.3 of this manual.
  174.   Color Crunch -> Flash the selected decrunch color when crunching, giving
  175.                   you an idea what the decrunching will look like (provided
  176.                   that you don't change any options just before saving to
  177.                   disk).
  178.   LED Crunch   -> Your power-LED flashes while crunching, just like the
  179.                   screencolors. Now, you can even turn off your monitor and
  180.                   still see when the cruncher has finished.
  181.   Multitask    -> Switch multitasking off to (sligtly) increase the crunching
  182.                   speed.
  183.   Paging       -> Pause and wait for mouse button when supervisor window
  184.                   fills up.
  185.   Overwrite    -> Don't prompt if it's ok to overwrite a file when saving.
  186.   Verify sleep -> When this switch is on you will be prompted if you are sure
  187.                   you want PowerPacker to go to sleep.
  188.   Sort files   -> Sort files in file requester.
  189.  
  190.      Use 'Save prefs' to save the preferences to your boot disk.  The
  191. preferences will be saved in the file 's:PowerPacker.prefs', this file will
  192. be enormous, euh, 6 bytes big.  When PowerPacker 2.3b is first started it
  193. will attempt to load this file and adjust the preferences.
  194.  
  195. NOTE: - While crunching, you can press both mousebuttons at the same
  196.         time to abort.
  197.       - Do *NOT* change disks when you are crunching with the multitasking
  198.         switched off !!!  The Amiga will crash !!!
  199.  
  200. 1.3.3 CRYPT
  201.      When the 'Encrypt Data' switch is on PowerPacker will not only crunch
  202. data files, it will also encrypt them so nobody else but you can decrunch
  203. them.  Just before crunching a data file PowerPacker will ask you for a
  204. password.  You will be presented with a string gadget with a special feature,
  205. it won't show you what you are typing !  After entering your password you
  206. will be asked to enter it again, this is done to verify that you haven't made
  207. a typing error (unless you make the same error twice :-).
  208.      You can also use the 'Last' gadget to re-enter your last password again,
  209. or the 'Abort' gadget to abort the encryption and just crunch the file.
  210.      When you try to load a crunched encrypted data file PowerPacker will
  211. once again prompt you for your password.  If you enter the correct one the
  212. data file will be decrypted and decrunched.  If you don't know the password,
  213. bad luck, there is no way you can decrunch this file !!
  214.  
  215. NOTE: - Encryption can currently not be used in a script.
  216.       - Your password can be up to 16 characters long, any character is
  217.         accepted, lowercase and uppercase are DIFFERENT !!!!
  218.       - Take care when using the 'Last' gadget, be sure to know what your
  219.         last password was.
  220.       - Don't forget your password !!  It is *IMPOSSIBLE* to decrypt a file
  221.         without the password !!!!!
  222.  
  223. 2. RECRUNCH
  224.  
  225. 2.1 HOW ?
  226.      This menu is provided for the people who were using another cruncher or
  227. an older version of PowerPacker.  Just select 'Recrunch File' or 'Decrunch
  228. Only' and load the file.  PowerPacker will start the correct decrunch
  229. algorithm.  If you selected 'Recrunch' PowerPacker will start to crunch the
  230. decrunched file.  If PowerPacker doesn't recognize the cruncher it will say
  231. so, no harm is done.  If you select 'Recrunch Always' PowerPacker will always
  232. recrunch, even if the file was crunched with this version of PowerPacker.
  233. Useful for recrunching files using a higher efficiency.  (e.g. recrunch a
  234. 'Fast' crunched file with 'Best')
  235.      Use the 'Change Color' item to change the decrunch color in an already
  236. crunched file to the current decrunch color.  Please note that the file will
  237. be changed on disk, nothing will be loaded into memory.
  238.      Crunchers currently supported are:  'ANC Cruncher', 'TNM Cruncher 1.1',
  239. 'Relokit 1.0', 'HQC Cruncher 2.0', 'MasterCruncher 3.0', 'DragPack 1.0' and
  240. older PowerPacker files.  If you'd like to see other crunchers supported,
  241. send me the cruncher and some programs crunched with it.  (Together with a
  242. contribution I hope).  If it is possible to develop a decrunch algorithm I
  243. will include it in the next version of PowerPacker.
  244.  
  245. 2.2 WHY ?
  246.      PowerPacker always crunches better than the 'ANC Cruncher', 'TNM
  247. Cruncher' and 'HQC Cruncher'.  It crunches better than 'Relokit' most of the
  248. time, but even if it doesn't, I advise you to recrunch because 'Relokit' has
  249. some serious disadvantages (e.g. while the decrunched file is running, the
  250. crunched version still eats memory).  In contrast PowerPacker only eats about
  251. 530 bytes while your file is running, and (of course) frees it afterwards.
  252.  
  253. NOTE: - If you want to recrunch a PowerPacker 1.1 or 2.0 crunched file,
  254.         PowerPacker just replaces the file header with the improved and
  255.         debugged 2.1+ header. (Unless you've selected 'Recrunch Always')
  256.       - The recrunch menu only supports command files !  You can't recrunch
  257.         data files from e.g. PowerPacker 1.1, sorry.
  258.       - 'Decrunch Only' is not 100% guaranteed for 'Relokit 1.0' files,
  259.         'Recrunch' however is 100% ok ! (It's a strange world ! :-)
  260.       - Several people sent me 'dirty' crunchers, these are crunchers that
  261.         use absolute addresses (an absolute TABOO !!!).  It is impossible
  262.         to develop a decrunch algorithm for these.  (In fact, nothing should
  263.         have been crunched with these crunchers in the first place !)
  264.  
  265. 3. THE HUNKLAB
  266.  
  267. 3.1 PREFERENCES
  268.      This menu is not really part of the PowerPacker crunch/decrunch routines
  269. but it wasn't worth writing a separate program for and a HunkLab is after all
  270. a very interesting utility.  You can e.g. use it to remove symbol and debug
  271. hunks from files that wouldn't crunch otherwise.
  272.  
  273.      You can force a program's code, data or BSS (uninitialised data) into
  274. chip ram or you can remove symbol tables and debug information just by
  275. toggling the marker on/off.  So in future, when you want your programs to be
  276. able to run on a one megabyte system, a simple click on the mousebutton will
  277. do.
  278.  
  279. 3.2 PROCESS FILE
  280.      'Process file' reads the file from disk and changes it according to your
  281. preferences.  To save the processed file, use 'Save' from the Project menu.
  282.      'Process & Crunch' will process the file and crunch the file afterwards
  283. (if possible).  To save use 'Save' in the Project menu.
  284.  
  285. NOTE: - Debug and symbol hunks are only used in debuggers, so you can safely
  286.         remove them from a program. (Unless you want to debug the program.)
  287.  
  288. 4. THE SCRIPT MENU
  289.      The script is something that will save you a lot of time, it allows you
  290. to record 80 different commands to be executed after each other.  It is ideal
  291. for crunching a lot of files overnight.  Menu options are:
  292.  
  293.      'Clear Script' and 'List Script':
  294.           will do just that.
  295.      'Script Log File':
  296.           is used to specify a file to redirect output to.  If you cancel
  297.           the requester no log file is used.
  298.      'Destination Dir':
  299.           is used to specify the directory to save to.  It is ghosted in
  300.           normal use.
  301.      'Start Recording':
  302.           is used to start the recording of the script. If the script was
  303.           empty you will be asked for the destination directory.
  304.               After selecting the destination you can start entering the
  305.           script commands.  Everything that is ghosted is not available as a
  306.           command.  Just enter everything as if you were actually using
  307.           PowerPacker.  When you e.g. choose 'Load' PowerPacker will ask a
  308.           list of files to be (de)crunched. Press 'CANCEL' to exit the
  309.           entry.
  310.           NOTE: - You can still change the source and destination dir while
  311.                   recording.
  312.           Every command you enter will be displayed in the supervisor window.
  313.      'Stop Recording':
  314.           is used to exit the recording mode.
  315.      'Delete Last':
  316.           will delete the last command after a confirmation.
  317.      'Execute Script':
  318.           will start the playback of the script commands.  You will be asked
  319.           if you want files that are already crunched with PowerPacker to be
  320.           skipped.  This way you can select all the files in a directory
  321.           without worrying about crunched files being decrunched.
  322.               If you press the menu button a requester will appear to ask you
  323.           if you want to abort the script execution.  After executing the
  324.           script a request to clear the script will appear.
  325.  
  326. NOTE: - It is advisable to let the filerequester buffer fill before you
  327.         start selecting files.  It is also better not to change the source
  328.         directory too often.
  329.       - The screen turns grey to indicate a script is executing.
  330.       - While executing a script, PowerPacker will always act destructive !
  331.         Files will allways be overwritten and deleted !!!
  332.  
  333. 5. THE SUPERVISOR WINDOW
  334.      This window displays all kind of useful information like the file
  335. status, crunch messages, and error messages.  You can follow all steps, from
  336. the original file that is loaded into memory, to the final crunched version
  337. on disk.  When an executable file is loaded, its hunk information is
  338. displayed.  This information is rather technical, but it can be useful for
  339. programmers.  If you're not interested, just ignore it.
  340.  
  341.      I think it might be useful to give a list of possible error messages:
  342.  
  343. (De)crunch :  Buffer overflow !
  344.                 (Crunched file is getting longer than original file)
  345.               Crunch aborted !
  346.                 (Crunching stopped by user or by buffer overflow)
  347.               No memory for decrunch buffer !
  348.               Out of memory !
  349.                 (Buy some more, try selling your WorkBench :-)
  350.               Sorry, can't crunch !
  351.                 (This is a polite program)
  352.               Can't find hunk_header.
  353.               Hunk not allowed in load file!
  354.               Unknown Hunk !
  355.                 (Not a command file)
  356.               Hunk not supported (yet ?) !
  357.                 (If it's a symbol or debug hunk, try removing it in HunkLab)
  358.               Nothing to save !
  359.                 (Buffer is empty)
  360.               Save Aborted !
  361.               Error reading file !
  362.               Can't open file !
  363.               Error writing data header !
  364.               Error writing buffer !
  365.               File not found !
  366.               Couldn't delete file !
  367.               Can't open file !
  368.                 (Disk errors)
  369.  
  370. Recrunch :    No need to recrunch 'PowerPacker 1.1' command file,
  371.               Replacing 1.1 decrunch header with 2.3 header...
  372.                 (2.1+ header is shorter and bugfree, 1.1 isn't !!)
  373.               No need to recrunch 'PowerPacker 2.0' command file,
  374.               Replacing 2.0 decrunch header with 2.3 header...
  375.                 (There was still a small bug in 2.0 header, so replace it.)
  376.               Not crunched with one of the supported crunchers !!
  377.                 (Or file isn't crunched at all !)
  378.               Sorry, can't recrunch !
  379.                 (Please don't sue me :-)
  380.  
  381. Process :     Sorry, can't process file !
  382.                 (File is probably not a command file)
  383.               Can't crunch file !
  384.                 (File contains unsupported hunks)
  385.  
  386. Script :      Script buffer full !! Please stop recording.
  387.                 (Script is limited to 80 commands, select 'Stop Recording')
  388.  
  389. 6. A SAMPLE SESSION
  390.      Now that I have explained PowerPacker's capabilities, it's time for
  391. a little demonstation.  Let's say we want to crunch the 'CLI' command in the
  392. System directory on your Workbench 1.2 disk.
  393.  
  394.      Select 'Pointer' in the Prefs/Decrunch Color menu (When I wrote this
  395. text, it was very late and I couldn't stand the other decrunch colors
  396. anymore !)
  397.  
  398.      Set 'Prefs' to 'Command file'.  Now select 'Load' in the Project menu
  399. (the file requester will appear), insert your WorkBench 1.2 disk and choose
  400. the 'CLI' command in the system directory.  Now you'll see a lot of hunk
  401. (or junk ?? :-) information about the CLI command:
  402.  
  404.      Scanning file 'df0:System/CLI'...
  405.      Loading command file...
  407.      Hunk_header (0x03F3)
  408.         9 hunks (0 to 8).
  409.      Hunk  0 : Hunk_code (0x03E9)     (524 bytes)
  410.                Hunk_reloc32 (0x03EC) 
  411.      Hunk  1 : Hunk_data (0x03EA)     (428 bytes, 0 BSS)
  412.      Hunk  2 : Hunk_code (0x03E9)     (472 bytes)
  413.                Hunk_reloc32 (0x03EC) 
  414.      Hunk  3 : Hunk_data (0x03EA)     (52 bytes, 0 BSS)
  415.      Hunk  4 : Hunk_code (0x03E9)     (16 bytes)
  416.      Hunk  5 : Hunk_code (0x03E9)     (0 bytes)
  417.      Hunk  6 : Hunk_code (0x03E9)     (196 bytes)
  418.                Hunk_reloc32 (0x03EC) 
  419.      Hunk  7 : Hunk_code (0x03E9)     (68 bytes)
  420.                Hunk_reloc32 (0x03EC) 
  421.      Hunk  8 : Hunk_data (0x03EA)     (0 bytes, 0 BSS)
  423.      Crunching command file...
  424.      Press left and right button to abort.
  425.      Crunching, please wait.
  426.                                                                              
  428.      The cruncher displays the percentage of the file already crunched and
  429. the gain so far. After some time your screen will look like this:
  430.  
  432.      100% crunched.
  433.      Done.
  434.      Original length : 2356 bytes.
  435.      Crunched length : 1204 (1776) bytes.
  436.      Gained 49% (1152 bytes) !
  437.                                                                              
  439.      The only thing you have to do now is save this back to disk as an
  440. executable file.  Now enjoy the crunched CLI command.
  441.  
  442. 7. POWERPACKER 2.3B & THE CLI
  443.      For your convenience, I have also written two CLI commands, one to
  444. crunch and one to decrunch data files.
  445.      From version 2.3 onwards the CLI commands use the magnificent ARP
  446. library !!!  This means they have been greatly enhanced:  wildcards are fully
  447. supported, options can be entered in any order, directories will be created
  448. when needed, etc...  Make sure the arp.library is in your LIBS:  directory
  449. when you run these commands.
  450.      A usage line is given by typing 'Crunch' or 'Decrunch' without
  451. arguments.  You'll get something like this:
  452.  
  453. 1> Crunch
  454. POWER-PACKER 2.3a Data Cruncher.
  455.   Written by Nico François (POWER PEAK)
  456. Usage : Crunch <source> <destination> [EFFICIENCY 1-5] [COLOR 0-4] [CRYPT]
  457.                                       [NOSUFF] [NOLED] [FORBID] [NOPER]
  458. With:
  459.   EFFICIENCY: 1 = Fast, 2 = Mediocre, 3 = Good (def), 4 = Very Good, 5 = Best
  460.   COLOR     : 0/1 = Color 0/1, 2 = Pointer (def), 3 = Scroll, 4 = None
  461.   CRYPT     : Encrypt file.
  462.   NOSUFFIX  : Don't attach '.pp' suffix to filename.
  463.   NOPER     : Don't print percentage.
  464.   NOLED     : Disable led crunch.
  465. Hit ^C to abort, ^D to abort crunching only.
  466.  
  467. 1> Decrunch
  468. POWER-PACKER 2.3a Data Decruncher.
  469.   Written by Nico François (POWER PEAK)
  470. Usage : Decrunch <source> <destination> [COLOR 0-4] [OPT B|F] [SKIP] [QUIET]
  471. With:
  472.    COLOR: 0/1 = Color 0/1, 2 = Pointer (def), 3 = Scroll, 4 = None
  473.    SKIP : Skip uncrunched files.
  474.    QUIET: Be quiet.
  475. If <destination> is '*' or is omited, files will be typed to Output().
  476. Options effective when typing:
  477.    OPT B will print a banner before and
  478.    OPT F will print a formfeed after each file.
  479. Hit ^C to abort, ^D to abort typing only.
  480.  
  481. 1>
  482.      These commands are useful to be included in your startup-sequence or to
  483. read crunched text files quickly.
  484.  
  485.   Some examples:
  486.  
  487.      Crunch df0:source/*.c TO ram:source COL 4 NOLED
  488.  
  489.      This will result in a crunching of every C program in the df0:source
  490. directory.  If the ram:source directory exists the files will be saved there,
  491. if it doesn't it will be created if there is more than one C program in
  492. df0:source.  The '.pp' suffix will be attached to the filenames.  The led
  493. will not flicker, no crunch color is used.
  494.  
  495.      Decrunch >PRT: QUIET dh0:progs/*.asm.pp OPT BF COL 3
  496.  
  497.      Every crunched assembler program will be decrunched and printed, before
  498. each file a banner will be printed, each file will start on a new page.  If
  499. the file is encrypted you will be prompted for a password.  It is very
  500. important that you use the QUIET option here, if you don't the copyright and
  501. information lines will also be printed.  The mouse pointer will flash while
  502. decrunching.
  503.  
  504. NOTE: - These commands only (de)crunch DATA files !!!!  (So to (de)crunch
  505.         executable files, you'll still have to use PowerPacker 2.3b).
  506.  
  507. 8. POWERPACKER 2.3B & OTHER PROGRAMS
  508.  
  509. 8.1 INTRODUCTION
  510.      This one is for the programmers among you !
  511.      From release 2.3 onwards the decrunch source is included.  I decided to
  512. do this so other programs could load data files crunched with PowerPacker.
  513. As an example I could refer to one of my other utilities : PPMore, this is a
  514. text viewing utility (like more, hence the name) that can also display ASCII
  515. files crunched with PowerPacker.
  516.      Source is presented as a support function 'PP_LoadData', this function
  517. will load a data file and will decrunch it if necessary.  When the file isn't
  518. crunched it'll just be loaded.  Encrypted files are also supported.
  519.      The source was written for Aztec C 3.6a.  If you want to compile it with
  520. Lattice you will have to seperate C and assembler, compile/assemble them
  521. separatly and link them together.  You can use this code for non-commercial
  522. programs as long as you leave my copyright notice intact.
  523.  
  524. 8.2 THE FUNCTION
  525.  
  526.   error = PP_LoadData (file, color, typeofmem, buffptr, lengthptr, password);
  527.  
  528.   with:
  529.      char *file;         filename of file to be loaded
  530.      UBYTE color;        decrunch color (see ppdata.h)
  531.      ULONG typeofmem;    type of memory to be allocated
  532.      UBYTE **buffptr;    address of buffer pointer variable
  533.      ULONG *lengthptr;   address of length variable
  534.      char *password;     pointer to password string or NULL
  535.  
  536.   Note:
  537.      - error and color codes are defined in <ppdata.h>.
  538.      - memory must be freed by caller after usage : FreeMem (buff, length);
  539.  
  540.      You have the following decrunch colors available:
  541.  
  542.           DECR_COL0      Decrunch in color 0
  543.           DECR_COL1         ''    '' color 1
  544.           DECR_POINTER      ''    '' the mouse pointer
  545.           DECR_SCROLL       ''    '' the scroll register
  546.           DECR_NONE      No decrunch color is used
  547.  
  548.      The following errors can occure:
  549.  
  550.           PP_LOADOK      No error, file loaded succesfully.
  551.           PP_LOCKERR     Couldn't lock file, file probably doesn't exist.
  552.           PP_OPENERR     Couldn't open file.
  553.           PP_READERR     Read error.
  554.           PP_NOMEMORY    No memory to allocate buffer for data file.
  555.           PP_CRYPTED     File is crypted and no password was provided.
  556.           PP_PASSERR     File is crypted and wrong password provided.
  557.  
  558. 8.3 LOADING ENCRYPTED FILES
  559.      To load encrypted files a password has to be provided to the function.
  560. First of all try to load the file with a NULL pointer for 'password', when
  561. you get the PP_CRYPTED error you know that the file is encrypted.  Then
  562. prompt the user for a password and call the function again with the same
  563. parameters, but now 'password' points to the password string.  If PP_LoadData
  564. returns PP_LOADOK the file was decrypted, if it returns PP_PASSERR the
  565. password was incorrect.  If it returns anything else some sort of error
  566. occured (see <ppdata.h> for the error codes).
  567.  
  568. 8.4 COMPILING AND LINKING
  569.      - If you use Aztec C you have one module to compile : ppdata.c
  570.  
  571.      cc [options] ppdata.c
  572.  
  573.      Use the same options you use in the other modules of your program.
  574. Compile the other modules of your program and link everything together:
  575.  
  576.      ln +q main.o ... ppdata.o -lc -o myprog
  577.  
  578.      - If you use Lattice C you will have to seperate the C source from the
  579. assembler source and compile/assemble them seperatly.  You will then get two
  580. object files.  When you then link everything together be sure to link with
  581. both these object files.  (I haven't tried it, but it should work)
  582.  
  583. 8.5 AN EXAMPLE
  584.      This small (incomplete) program shows you how to use the support
  585. function in your programs.
  586.  
  587. /*********
  588. * test.c *
  589. *********/
  590.  
  591. #include <exec/types.h>
  592. ...
  593. #include <ppdata.h>
  594.  
  595. UBYTE *buffer = NULL;
  596. ULONG bufferlength;
  597. UBYTE password[17];
  598.  
  599. main()
  600. {
  601.      int error;
  602.  
  603.      error = PP_LoadData ("df0:doc/Packer.doc.pp", DECR_POINTER, MEMF_PUBLIC,
  604.           &buffer, &bufferlength, NULL);     /* Don't forget the '&' !!!!! */
  605.      if (error != PP_LOADOK) switch (error) {
  606.           case PP_LOCKERR:
  607.                puts ("file not found !!!");
  608.                FreeStuffAndExit();
  609.           case PP_LOADERR:
  610.                puts ("loading error !!!");
  611.                FreeStuffAndExit();
  612.           case PP_NOMEMORY:
  613.                puts ("out of memory !!!");
  614.                FreeStuffAndExit();
  615.           ...
  616.           case PP_CRYPTED:
  617.                /* prompt the user for a password (max 16 chars) */
  618.                ...
  619.                error = PP_LoadData ("df0:docs/Packer.doc.pp", DECR_POINTER,
  620.                     MEMF_PUBLIC, &buffer, &bufferlength, password);
  621.                if (error == PP_PASSERR) {
  622.                     puts ("incorrect password !!!");
  623.                     FreeStuffAndExit();
  624.                     }
  625.                else if (error != PP_LOADOK) {
  626.                     puts ("correct password, but couldn't load !!!");
  627.                     FreeStuffAndExit();
  628.                     }
  629.                break;
  630.           }
  631.      /* now do something with the data file loaded at addr 'buffer' and with
  632.         length 'bufferlength' */
  633.      ...
  634.      /* DO NOT FORGET TO FREE THE MEMORY !! */
  635.      FreeMem (buffer, bufferlength);
  636. }
  637.  
  638. FreeStuffAndExit()
  639. {
  640.      /* free all your resources */
  641.      ...
  642.      exit (0);
  643. }
  644.                                              Enjoy this program !!!
  645.  
  646. PROGRAM HISTORY:
  647.  
  648. VERSION 1.0a
  649.      First release.
  650.  
  651. VERSION 1.1a
  652.      Fixed bugs.
  653.      Improved crunch algorithm by about 5%.
  654.      'Delete' and 'Multitask' added.
  655.      Better menu structure.
  656.      Improved the file requester.
  657.      Written CLI commands.
  658.  
  659. VERSION 2.0a
  660.      Fixed some more bugs.
  661.      Added buffer and automatic device-list to the file requester.
  662.      Added 'LED Crunch', useful for turning the monitor off while crunching,
  663.      and 'Paging'.
  664.      New header, bug fixed. (1.1 didn't free mem when started from WorkBench)
  665.      Added the hunklab.
  666.      Improved CLI commands.
  667.  
  668. VERSION 2.1a
  669.      Fixed last bug in header (2.0 crashed when you were out of memory, oops)
  670.      Added script feature, now possible to crunch files overnight.
  671.      Improved requesters.
  672.      Automatic crunch/decrunch.
  673.      Improved menu structure considerably.
  674.      Intelligent recrunch implemented.
  675.      Automatic crunch/decrunch.
  676.      Added 'Color Crunch' option.
  677.      New efficiency 'Best' added.
  678.  
  679. VERSION 2.1b
  680.      Bug fixed in script abort.
  681.      Added ability to open a log file during script execution.
  682.      Now possible to recrunch PowerPacker files with a higher efficiency.
  683.      Recrunch detects unsupported crunchers a lot faster.
  684.      PowerPacker now automatically opens a PAL/NTSC screen.
  685.  
  686. VERSION 2.2a
  687.      All known bugs (or better, undocumented features) fixed.
  688.      'Sleep' mode implemented, useful for multitasking freaks.
  689.      While crunching the gain percentage so far is displayed.
  690.      Recrunch now supports 'HQC Cruncher 2.0', 'MasterCruncher 3.0'
  691.        and 'Dragpack 1.0'.
  692.      New graphics in title.
  693.  
  694. VERSION 2.3a
  695.      PowerPacker detaches itself from the CLI, so the CLI window can be
  696.        closed or used for other things.
  697.      CLI commands are greatly enhanced, they now use ARP.
  698.      New switch : 'Overwrite' to surpress 'OK to overwrite ?' request.
  699.      File requester now able to sort files, 'Sort files' switch.
  700.      By popular demand: encryption of data files is now possible using the
  701.        new 'Encrypt Data' switch. Encryption should be IMPOSSIBLE to crack !!
  702.      Also by popular demand: Now possible to save preferences to boot disk.
  703.      More memory efficient decrunch and recrunch of PowerPacker files.
  704.      Decrunch source included, so other programs could be written that
  705.        would load data files crunched with PowerPacker.
  706.      'Data Suffix' switch to improve adding/removing of '.pp' suffix.
  707.      Decrunch color default 'Pointer'.
  708.      Improved scanning of files when loading or recrunching.
  709.      Fixed small bug (version 2.2a lost 256 bytes every time it was run).
  710.      More info in about window.
  711.  
  712. VERSION 2.3b
  713.      Added 'Change Color' in 'Recrunch' menu to change the decrunch color
  714.        of an already crunched file.
  715.      PowerPacker now starts up a process with priority -1.  It now no longer
  716.        slows down the rest of the system (e.g. a CLI) when crunching.
  717.      New 'Verify sleep' switch to toggle the requester that verifies the
  718.        sleep function on/off.
  719.      Now possible to skip files already crunched with PowerPacker in script.
  720.      Bug fixed in 'Recrunch', ANC files were no longer recognized. Oops :-)
  721.